home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 July: Mac OS SDK / Dev.CD Jul 99 SDK1.toast / Development Kits / Mac OS / AIAT / Headers / Storage / IAStorable.h < prev    next >
Encoding:
Text File  |  1998-04-16  |  5.2 KB  |  141 lines  |  [TEXT/CWIE]
  1. // IAStorable.h -- Some base classes for objects that may reside in a IAStorage.
  2. //    Copyright:    © 1994 - 1998 by Apple Computer, Inc., all rights reserved.
  3.  
  4.  
  5. #pragma once
  6. #ifndef IAStorable_h
  7. #define IAStorable_h
  8.  
  9. #pragma import on
  10.  
  11. #if PRAGMA_STRUCT_ALIGN
  12.     #pragma options align=power
  13. #endif
  14.  
  15. #include "IAStorage.h"
  16.  
  17. #pragma IA_BEGIN_EXPORTS
  18.  
  19. // the base class for storable objects
  20. class IAStorable : public IAObject {
  21. public:
  22.     IA_INLINE            ~IAStorable() IA_INLINE_DEF()                // no-op dtor def
  23.     // returns a copy of an object & any memory it points to
  24.     virtual IAStorable*    DeepCopy() const = 0;
  25.     // returns the number of bytes in an objects serialization
  26.     virtual IABlockSize    StoreSize() const = 0;
  27.     // serializes the object to output, writing StoreSize() bytes to output
  28.     virtual void        Store(IAOutputBlock* output) const = 0;
  29.     // deserializes and returns a new object -- reading StoreSize() bytes from input
  30.     virtual IAStorable*    Restore(IAInputBlock* input) const = 0;
  31. protected:
  32.     // methods to simplify subclassing
  33.     // these are called on a new instance to fill in its slots
  34.     virtual void        DeepCopying(const IAStorable* source);                    // no-op impl
  35.     virtual void        Restoring(IAInputBlock* input, const IAStorable* proto);// no-op impl
  36. };
  37.  
  38. /*
  39.  
  40. /// implementations of DeepCopy() and Restore() should work as follows:
  41.  
  42. IAStorable* SubClass::DeepCopy() const {
  43.     SubClass* sub = new SubClass;                // allocate instance
  44.     sub->DeepCopying(this);                        // copy slots
  45.     return sub;                                    // return it
  46. }
  47. void SubClass::DeepCopying(const IAStorable* source) {
  48.     SuperClass::DeepCopying(source);            // copy super slots
  49.     // ... copy subclass slots from source ...
  50. }
  51. */
  52.  
  53. // a subclass for IAStorable's which may be sorted
  54. class IAOrderedStorable : public IAStorable {
  55. public:
  56.     IA_INLINE            ~IAOrderedStorable() IA_INLINE_DEF()    // no-op dtor definition
  57.     // returns true iff and object belongs before neighbor 
  58.     virtual bool        LessThan(const IAOrderedStorable* neighbor) const = 0;
  59.     // returns true iff an object is equal to neighbor
  60.     virtual bool        Equal(const IAOrderedStorable* neighbor) const = 0;
  61. };
  62.  
  63.  
  64. // IAOrderedStorableSet: a sorted set of IAOrderedStorable's
  65.  
  66. class IAOrderedStorableIterator : public IAObject {
  67. public:
  68.     IA_INLINE            ~IAOrderedStorableIterator() IA_INLINE_DEF()// no-op dtor def
  69.     // Advances the iterator to the next entry in the set and returns it.
  70.     // Returns NULL at the end of the set.
  71.     // Note: this returns a DeepCopy() of the object.  Clients must delete.
  72.     virtual IAOrderedStorable*    Next() = 0;
  73. };
  74.  
  75. // When cloneStoreStream set true, OrderedStorableSets will use cloned StoreStreams.  false by default.
  76.  
  77. extern     bool     IACloneOSSetStoreStreams;
  78.  
  79. class IAOrderedStorableSet : public IAObject {
  80. public:
  81.     IA_INLINE                ~IAOrderedStorableSet() IA_INLINE_DEF()// no-op dtor def
  82.     // initializes a new, empty IAOrderedStorable rooted at the named block, leaving it open.
  83.     // a cloned IAStoreStream may be requested to improve threaded throughput
  84.     virtual void            Initialize(IAStorage* storage, IABlockID block,
  85.                                        bool cloneStoreStream = IACloneOSSetStoreStreams) = 0;
  86.     // flushes any cached changes to disk -- should be called before Commit()
  87.     virtual void            Flush() = 0;
  88.     // purges any cached data from memory
  89.     virtual void            Purge() = 0;
  90.     // opens an existing IAOrderedStorable rooted at the named block
  91.     // a cloned IAStoreStream may be requested to improve threaded throughput
  92.     virtual void            Open(IAStorage* storage, IABlockID block,
  93.                                  bool writable = true,
  94.                                  bool cloneStoreStream = IACloneOSSetStoreStreams) = 0;
  95.     // frees all storage associated with the set
  96.     virtual void            Destroy() = 0;
  97.  
  98.     // puts an object into the set, replacing any there.  object is destroyed. 
  99.     virtual bool            Put(IAOrderedStorable* obj) = 0;
  100.     // gets an objects from the set, if any such exists, returning a DeepCopy().
  101.     virtual IAOrderedStorable* Get(const IAOrderedStorable* key) = 0;
  102.     // removes an object from the set, if any
  103.     virtual bool            Remove(const IAOrderedStorable* key) = 0;
  104.  
  105.     // returns the number of entries in the set
  106.     virtual uint32            Count() = 0;
  107.     // returns the total number of bytes of storage allocated by the set
  108.     virtual uint32            TotalSize() = 0;
  109.  
  110.     // creates an iterator positioned before the first element
  111.     virtual IAOrderedStorableIterator*        MakeIterator() = 0;
  112.     // creates an iterator positioned at or after the named element
  113.     virtual IAOrderedStorableIterator*        MakeIterator(const IAOrderedStorable* key) = 0;
  114.  
  115.     // returns an estimate of the fraction of the set which lies before the named key.
  116.     // this is useful (with TotalSize()) for estimating the cost of range iteration.
  117.     virtual float            PositionEstimate(const IAOrderedStorable* key) = 0;
  118.  
  119.     // in the debug libraries, prints some info about the set to the standard output
  120.     virtual void            ReportStats();
  121.     // Get the lock or mutex for committing the entire storage as one transaction
  122.     virtual    IAMutex*        GetMutex() = 0;
  123. };
  124.  
  125. IAExceptionCode                    OrderedStorableSetEntryTooBig = 'VSBE';
  126.  
  127. // Returns an instance of the default implementation of IAOrderedStorableSet -- a B-Tree.
  128. // 'proto' is used to call Restore().  It is deleted when the set is deleted.
  129. IAOrderedStorableSet*        IAMakeOrderedStorableSet(IAOrderedStorable* proto);
  130.  
  131. extern uint32 OrderedStorableSetType;
  132.  
  133. #pragma IA_END_EXPORTS
  134.  
  135. #if PRAGMA_STRUCT_ALIGN
  136.     #pragma options align=reset
  137. #endif
  138.  
  139. #pragma import reset
  140. #endif
  141.